home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / FileHndlr.3 < prev    next >
Text File  |  1995-07-25  |  8KB  |  133 lines
  1.  
  2.  
  3.  
  4.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333))))      TTTTkkkk (((( ))))       TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tk_CreateFileHandler,   Tk_DeleteFileHandler   -   associate
  12.           procedure callback with a file or device
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  16.  
  17.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr(_i_d, _m_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19.           TTTTkkkk____DDDDeeeelllleeeetttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr(_i_d)
  20.  
  21.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  22.           int           _i_d           (in)      Integer identifier  for
  23.                                                an  open file or device
  24.                                                (such  as  returned  by
  25.                                                ooooppppeeeennnn system call).
  26.  
  27.           int           _m_a_s_k         (in)      Conditions under  which
  28.                                                _p_r_o_c  should be called:
  29.                                                OR-ed  combination   of
  30.                                                TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE,
  31.                                                TTTTKKKK____WWWWRRRRIIIITTTTAAAABBBBLLLLEEEE,        and
  32.                                                TTTTKKKK____EEEEXXXXCCCCEEEEPPPPTTTTIIIIOOOONNNN.
  33.  
  34.           Tk_FileProc   *_p_r_o_c        (in)      Procedure   to   invoke
  35.                                                whenever  the  file  or
  36.                                                device indicated by  _i_d
  37.                                                meets   the  conditions
  38.                                                specified by _m_a_s_k.
  39.  
  40.           ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary      one-word
  41.                                                value to pass to _p_r_o_c.
  42.      _________________________________________________________________
  43.  
  44.  
  45.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  46.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr arranges for _p_r_o_c to be invoked in  the
  47.           future  whenever  I/O  becomes  possible  on  a  file  or an
  48.           exceptional condition exists for  the  file.   The  file  is
  49.           indicated   by  _i_d,  and  the  conditions  of  interest  are
  50.           indicated by _m_a_s_k.  For example,  if  _m_a_s_k  is  TTTTKKKK____RRRREEEEAAAADDDDAAAABBBBLLLLEEEE,
  51.           then  _p_r_o_c  will  be  called when the file is readable.  The
  52.           callback   to   _p_r_o_c   is   made   by   TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt,    so
  53.           TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr   is   only  useful  in  programs  that
  54.           dispatch events through TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt or  through  other  Tk
  55.           procedures that call TTTTkkkk____DDDDooooOOOOnnnneeeeEEEEvvvveeeennnntttt, such as TTTTkkkk____MMMMaaaaiiiinnnnLLLLoooooooopppp.
  56.  
  57.           _P_r_o_c should have arguments and result that  match  the  type
  58.           TTTTkkkk____FFFFiiiilllleeeePPPPrrrroooocccc:
  59.                typedef void Tk_FileProc(
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333))))      TTTTkkkk (((( ))))       TTTTkkkk____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.                     ClientData _c_l_i_e_n_t_D_a_t_a,
  75.                     int _m_a_s_k);
  76.           The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  77.           argument  given  to  TTTTccccllll____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr when the callback
  78.           was  created.   Typically,  _c_l_i_e_n_t_D_a_t_a  points  to  a   data
  79.           structure  containing application-specific information about
  80.           the file.  _M_a_s_k is an integer mask indicating which  of  the
  81.           requested  conditions actually exists for the file;  it will
  82.           contain a subset  of  the  bits  in  the  _m_a_s_k  argument  to
  83.           TTTTccccllll____CCCCrrrreeeeaaaatttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr.
  84.  
  85.           There may exist only one handler for a given file at a given
  86.           time.   If  TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEEvvvveeeennnnttttHHHHaaaannnnddddlllleeeerrrr  is  called when a handler
  87.           already exists for _i_d, then the _m_a_s_k, _p_r_o_c,  and  _c_l_i_e_n_t_D_a_t_a
  88.           for  the  new  call  to  TTTTkkkk____CCCCrrrreeeeaaaatttteeeeEEEEvvvveeeennnnttttHHHHaaaannnnddddlllleeeerrrr  replace  the
  89.           information that was previously recorded.
  90.  
  91.           TTTTkkkk____DDDDeeeelllleeeetttteeeeFFFFiiiilllleeeeHHHHaaaannnnddddlllleeeerrrr  may  be  called  to  delete  the  file
  92.           handler  for _i_d;  if no handler exists for the file given by
  93.           _i_d then the procedure has no effect.
  94.  
  95.           The purpose of file handlers is to enable an application  to
  96.           respond to X events and other events while waiting for files
  97.           to become ready for I/O.  For this to  work  correctly,  the
  98.           application  must  use  non-blocking  I/O  operations on the
  99.           files  for  which  handlers  are  declared.   Otherwise  the
  100.           application may be put to sleep if it specifies too large an
  101.           input or  output  buffer;  while  waiting  for  the  I/O  to
  102.           complete  the  application  won't  be  able to service other
  103.           events.  In BSD-based UNIX systems, non-blocking I/O can  be
  104.           specified  for  a  file using the ffffccccnnnnttttllll kernel call with the
  105.           FFFFNNNNDDDDEEEELLLLAAAAYYYY flag.
  106.  
  107.  
  108.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  109.           callback, file, handler
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.